<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="utf-8">
    <title>YUI Global Object</title>
    <link rel="stylesheet" href="http://yui.yahooapis.com/3.4.0pr3/build/cssgrids/grids-min.css">
    <link rel="stylesheet" href="../assets/css/main.css">
    <link rel="stylesheet" href="../assets/vendor/prettify/prettify-min.css">
    <script src="../../build/yui/yui-min.js"></script>
</head>
<body>

<div id="doc">
    <h1>YUI Global Object</h1>

    
        <a href="#toc" class="jump">Jump to Table of Contents</a>
    

    <div class="yui3-g">
        <div id="main" class="yui3-u">
            <div class="content"><div class="intro">
    <p>The YUI module is the single core dependency for all YUI 3 implementations.  It must be included on all pages that use YUI &mdash; and it is the only dependency required to start writing YUI code.  The YUI module contains loader functionality and a dependency calculator, allowing it to serve as a "seed" for your implementation.  You provide the YUI module list you're using and the code that makes use of those modules; YUI will fetch all necessary components in a single, optimized HTTP request before executing your dependent code.  While you may use some of the script- and CSS-loading facilities of the YUI module in your own implementation, this module's core purpose is to serve as a small seed from which complex, highly modular implementations can grow.</p>
    <p>The YUI module creates a global YUI object.  This object is instantiable, and it is used to create YUI instances to which are bound specific functional modules.  A page can share a single YUI instance or can use different, insular instances for each piece of functionality on the page.</p>
</div>


<p>The YUI Global object is provided by one of our seed files:</p>

<h2 id="loader-seed">The Loader Seed</h2>
<pre class="code prettyprint">&lt;script src=&quot;http:&#x2F;&#x2F;yui.yahooapis.com&#x2F;3.4.0&#x2F;build&#x2F;yui&#x2F;yui-min.js&quot;&gt;&lt;&#x2F;script&gt;</pre>


<p>This seed file contains everything you need to fetch/use YUI core modules. It includes our dynamic script loader as well as all of the meta-data required to load additional YUI modules.</p>


<h2 id="base-seed">The Base Seed</h2>
<pre class="code prettyprint">&lt;script src=&quot;http:&#x2F;&#x2F;yui.yahooapis.com&#x2F;3.4.0&#x2F;build&#x2F;yui-base&#x2F;yui-base-min.js&quot;&gt;&lt;&#x2F;script&gt;</pre>


<p>This seed file contains the core items you need to use YUI core modules. It also includes the capability to fetch our dynamic script loader. <em>This seed was our old <code>yui.js</code></em></p>

<h2 id="why">Why the namespace change?</h2>
<ol>
    <li><strong>Backward Compatibility</strong>: With the change from <code>YAHOO</code> to <code>YUI</code> we are guaranteed not to break backward compatibility. This allows you to use both YUI 2 and YUI 3 on
    the same page without fear of breaking existing code.</li>
    <li><strong>Sandboxing</strong>: The new YUI Global Object is now smarter than ever, allowing you to create an instance of YUI in your own namespace and only load the modules that you need.
    It makes it easier for multiple developers to work on different parts of the page with different modules with less worry of them stepping on each other's toes.</li>
    <li><strong>Versioning</strong>: If another version of YUI is loaded on the page, it will not change objects used in
    existing YUI instances.  Both versions of YUI will operate with the corresponding versions of the reqested YUI modules without impacting each other.</li>



    <li><strong>More Dynamic</strong>: With Loader built into the core, loading files when you need them just got easier.</li>
    <li><strong>Selector Powered</strong>: Using Selector as its base for node handling, you now get more power and ease of use for free.</li>
    <li><strong>Event Normalization</strong>: With the new Event Facade, you get maximum event normalization for cleaner cross browser code.</li>
</ol>


<h2 id="core">YUI Core</h2>
<p>The YUI Global Object is an instantiatable object that allows you to create as many YUI instances as you need. Each completely configurable and loaded with only the modules that you need.</p>

<pre class="code prettyprint">YUI().use(&#x27;node&#x27;, function(Y) {
    Y.one(&#x27;#demo&#x27;);
});</pre>


<p>All of this functionality is available in the YUI Core:</p>

<table>
    <thead>
        <tr>
            <th>YUI 3 Component</th>
            <th>Module</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td>Array Operations</td><td>array</td>
        </tr>
        <tr>
            <td>YUI Core</td><td>core</td>
        </tr>
        <tr>
            <td>JavaScript language helper methods</td><td>lang</td>
        </tr>
        <tr>
            <td>Periodic execution method</td><td>later</td>
        </tr>
        <tr>
            <td>Logging support</td><td>log</td>
        </tr>
        <tr>
            <td>Object Operations</td><td>object</td>
        </tr>
        <tr>
            <td>Browser Sniffing</td><td>ua</td>
        </tr>
        <tr>
            <td>YUI Object</td><td>yui</td>
        </tr>
        <tr>
            <td>Dynamic script and css loading</td><td>get</td>
        </tr>
        <tr>
            <td>YUI Loader</td><td>loader</td>
        </tr>
    </tbody>
</table>

<h2 id="use">Use method</h2>
<p>The <code>use</code> method allows you to choose the modules that you want loaded into your YUI instance. You can pick and choose what you need, you don't have to load everything that was included on the page.</p>

<pre class="code prettyprint">YUI().use(&#x27;dd-drop&#x27;, &#x27;anim&#x27;, function(Y) {
    &#x2F;&#x2F; Y.DD is available
    &#x2F;&#x2F; Y.Anim is available
});

YUI().use(&#x27;anim&#x27;, function(Y) {
    &#x2F;&#x2F; Y.DD is NOT available
    &#x2F;&#x2F; Y.Anim is available
});</pre>


<h2 id="use-callback">Use callback</h2>
<p>You can pass a function in as the last argument to <code>use</code>. This function will execute after the YUI instance loads all the modules.
This is required if you do not have all dependencies on the page.</p>
<p>The callback method has one argument passed, the YUI instance that we are dealing with. In this function you know that all the modules have been loaded and it's ok to use them.</p>

<pre class="code prettyprint">YUI().use(&#x27;animation&#x27;, function(Y) {
    &#x2F;&#x2F; Y.Anim is available
});</pre>


<h2 id="use-shorthand">Use shorthand</h2>
<p>The <code>use</code> method contains a shorthand reference for all modules on the page. It uses the <code>*</code> as the module name.</p>
<p>This will load every module that is included on the page.</p>

<pre class="code prettyprint">YUI().use(&#x27;*&#x27;, function(Y) {
    &#x2F;&#x2F; Implementation code
});</pre>



<h2 id="static-inclusion-vs-dynamic-loading">Static inclusion vs. dynamic loading</h2>
<p>YUI automatically tries to complete itself when missing dependencies are detected.
   When dynamically loading the dependencies, the callback passed to <code>use</code>
   will be executed <em>asynchronously</em>.  If you statically include all of the
   library requirements (or all were previously loaded by another means), the
   use() callback will execute synchronously.  The purpose of the callback is so
   that it doesn't matter to the implementation whether the operation was synchronous
   or not.  Code immediately following the <code>use</code> statement will not have
   access to any of the requested modules if anything has to be dynamically loaded.
   You can prevent YUI from automatically trying to obtain missing dependencies by setting the
   YUI config <code>bootstrap</code> to false.</p>


<h2 id="modulelist">Module List</h2>
<p>Here is a partial list of the modules and their descriptions.</p>
<table>
    <thead>
        <tr>
            <th>YUI 3 Component</th>
            <th>Module</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td>Animation</td><td>anim</td>
        </tr>
        <tr>
            <td>Attribute Engine</td><td>attribute</td>
        </tr>
        <tr>
            <td>Class Builder</td><td>base</td>
        </tr>
        <tr>
            <td>Collection Utilities</td><td>collection</td>
        </tr>
        <tr>
            <td>Drag &amp; Drop</td><td>dd</td>
        </tr>
        <tr>
            <td>DOM Element Utilites</td><td>dom</td>
        </tr>
        <tr>
            <td>DOM Event Utilities</td><td>event</td>
        </tr>
        <tr>
            <td>Custom Event Engine</td><td>event-custom</td>
        </tr>
        <tr>
            <td>IO (XHR/XDR)</td><td>io</td>
        </tr>
        <tr>
            <td>JSON</td><td>json</td>
        </tr>
        <tr>
            <td>HTML Element Wrapper</td><td>node</td>
        </tr>
        <tr>
            <td>Support for non-blocking iterative operations</td><td>async-queue</td>
        </tr>
    </tbody>
</table>


<h2 id="yuiadd">Creating Custom Modules with YUI.add</h2>
<p><code>YUI.add</code> is a static global method that is
the single entry point for first class YUI modules.  This method
registers the module so that it can attached to a YUI instance
via the <code>use</code> method.  Modules registered this way
are dynamically attached during the <code>use</code> phase, so
they can be fully protected by the YUI sandbox.</p>
<p>During the <code>use</code> phase, the function passed to
<code>YUI.add</code> is executed.  It receives the YUI instance
as a parameter, and this can be used to add functionality to
the instance.</p>
<p>While you can add the module wrapper to your code yourself,
the <a href="http://yuilibrary.com/projects/builder">YUI Build Tool</a>
can wrap your code for you (it can also minify and lint your code, among
other things).
<p>The third parameter is a version identifier for your module.  This
is not the YUI version you are targeting</p>
<p>The fourth parameter is an optional metadata object.  This is read
by YUI when <code>YUI.add</code> executes -- it is used to fill in the
dependency information if this information was not previously provided
in the loader metadata provided to the YUI instance.  See below for
information about dynamically loading modules.  Dependencies are declared
via the <code>requires</code> attribute.  The <code>use</code> attribute
describes a module/submodule relationship -- when you build a YUI
module with submodules, the built module file will have the entire
YUI.add wrapped content for each submodule.  The <code>use</code> attribute
informs YUI that these modules must be used when the parent module is.

<pre class="code prettyprint">YUI.add(&#x27;mymodules-mod1&#x27;, function(Y) {

    Y.namespace(&#x27;mynamespace&#x27;);

    Y.mynamespace.Mod1 = function() {
        &#x2F;&#x2F; expose an API
    };

}, &#x27;0.1.1&#x27; &#x2F;* module version *&#x2F;, {
    requires: [&#x27;base&#x27;]
});</pre>


<h2 id="loader">Loader</h2>
<p>Loader's functionality is now built into the YUI Global Object
   (as long as it's on the page) and puts its power behind the
   <code>YUI().use</code> method.</p>
<p>If you request a module that is not loaded on the page
(or a dependency that is not loaded), loader will fetch a copy
of that module (and its dependencies) and attach them to your
YUI instance.</p>

<pre class="code prettyprint">YUI({
       lang: &#x27;ko-KR,en-GB,zh-Hant-TW&#x27;, &#x2F;&#x2F; languages in order of preference
       base: &#x27;..&#x2F;..&#x2F;build&#x2F;&#x27;, &#x2F;&#x2F; the base path to the YUI install.  Usually not needed because the default is the same base path as the yui.js include file
       charset: &#x27;utf-8&#x27;, &#x2F;&#x2F; specify a charset for inserted nodes, default is utf-8
       loadOptional: true, &#x2F;&#x2F; automatically load optional dependencies, default false
       combine: true, &#x2F;&#x2F; use the Yahoo! CDN combo service for YUI resources, default is true unless &#x27;base&#x27; has been changed
       filter: &#x27;raw&#x27;, &#x2F;&#x2F; apply a filter to load the raw or debug version of YUI files
       timeout: 10000, &#x2F;&#x2F; specify the amount of time to wait for a node to finish loading before aborting
       insertBefore: &#x27;customstyles&#x27;, &#x2F;&#x2F; The insertion point for new nodes
       &#x2F;&#x2F; one or more external modules that can be loaded along side of YUI.  This is the only pattern
       &#x2F;&#x2F; that was supported in 3.0.0 for declaring external modules.  3.1.0 adds &#x27;groups&#x27; support,
       &#x2F;&#x2F; which is an easier way to define a group of modules.  See below.
       modules:  {
           yui2_yde_datasource: {
               fullpath: &#x27;http:&#x2F;&#x2F;yui.yahooapis.com&#x2F;combo?2.7.0&#x2F;build&#x2F;yahoo-dom-event&#x2F;yahoo-dom-event.js&amp;2.7.0&#x2F;build&#x2F;datasource&#x2F;datasource-min.js&#x27;
           },
           yui_flot: {
               fullpath: &#x27;http:&#x2F;&#x2F;bluesmoon.github.com&#x2F;yui-flot&#x2F;yui.flot.js&#x27;,
               requires: [&#x27;yui2_yde_datasource&#x27;]
           }
       },

       &#x2F;&#x2F; one or more groups of modules which share the same base path and
       &#x2F;&#x2F; combo service specification.
       groups: {
           &#x2F;&#x2F; Note, while this is a valid way to load YUI2, 3.1.0 has intrinsic
           &#x2F;&#x2F; YUI 2 loading built in.  See the examples to learn how to use
           &#x2F;&#x2F; this feature.
           yui2: {
               combine: true,
               base: &#x27;http:&#x2F;&#x2F;yui.yahooapis.com&#x2F;2.8.0r4&#x2F;build&#x2F;&#x27;,
               comboBase: &#x27;http:&#x2F;&#x2F;yui.yahooapis.com&#x2F;combo?&#x27;,
               root: &#x27;2.8.0r4&#x2F;build&#x2F;&#x27;,
               modules:  { &#x2F;&#x2F; one or more external modules that can be loaded along side of YUI
                   yui2_yde: {
                       path: &quot;yahoo-dom-event&#x2F;yahoo-dom-event.js&quot;
                   },
                   yui2_anim: {
                       path: &quot;animation&#x2F;animation.js&quot;,
                       requires: [&#x27;yui2_yde&#x27;]
                   }
               }
           }
       }
}).use(&#x27;dd&#x27;, &#x27;yui_flot&#x27;, function(Y) {
    &#x2F;&#x2F; All YUI modules required to get drag and drop to work are now loaded.
});</pre>


<p>The valid configuration options for Loader are as follows:<p>
<ul>
    <li><code>lang</code>: The list of preferred languages, as BCP 47 language tags, in order of preference.
    The loader uses this list to determine the best language to use for modules with
    language sensitive behavior and to load the necessary resource bundles.
    See the <a href="../intl/">Internationalization</a> module for more information.</li>
    <li><code>base</code>: The base dir</li>
    <li><code>comboBase</code>: The YUI combo service base dir. Ex: http://yui.yahooapis.com/combo?</li>
    <li><code>root</code>: The root path to prepend to module names for the combo service. Ex: 2.5.2/build/</li>
    <li><code>filter</code>: A filter to apply to result urls.  This filter will modify the default
        path for all modules.  The default path for the YUI library is the
        minified version of the files (e.g., event-min.js).  The filter property
        can be a predefined filter or a custom filter.  The valid predefined
        filters are:
        <ul>
            <li><code>DEBUG</code>: Selects the debug versions of the library (e.g., event-debug.js). </li>
            <li><code>RAW</code>: Selects the non-minified version of the library (e.g., event.js).</li>
        </ul>
        You can also define a custom filter, which must be an object literal
        containing a search expression and a replace string:
        <pre>
        myFilter: &#123;
        'searchExp': "-min\\.js",
        'replaceStr': "-debug.js"
        &#125;
        </pre>
    </li>
    <li><code>combine</code>: Use the YUI combo service to reduce the number of http connections required to load your dependencies</li>
    <li><code>ignore</code>: A list of modules that should never be dynamically loaded</li>
    <li><code>force</code>: A list of modules that should always be loaded when required, even if already present on the page</li>
    <li><code>insertBefore</code>: Node or id for a node that should be used as the insertion point for new nodes</li>
    <li><code>charset</code>: charset for dynamic nodes</li>
    <li><code>jsAttributes</code>: attributes to apply to dynamic script nodes</li>
    <li><code>cssAttributes</code>: attributes to apply to dynamic link nodes</li>
    <li><code>timeout</code>: number of milliseconds before a timeout occurs when dynamically loading nodes.  in not set, there is no timeout</li>
    <li><code>context</code>: execution context for all callbacks</li>
    <li><code>modules</code>:  A list of module definitions.  The valid module configuration data is as follows:
        <ul>
            <li><code>name</code>:       required, the component name</li>
            <li><code>type</code>:       required, the component type (js or css)</li>
            <li><code>path</code>:       required if fullpath is not specified, the path to the script from "base"</li>
            <li><code>fullpath</code>:   required if path isn't specified, the full path to the script.  "base" will not be used to build the url</li>
            <li><code>requires</code>:   array of modules required by this component</li>
            <li><code>optional</code>:   array of optional modules for this component</li>
            <li><code>supersedes</code>: array of the modules this component replaces</li>
            <li><code>after</code>:      array of modules the components which, if present, should be sorted above this one</li>
            <li><code>rollup</code>:     the number of superseded modules required for automatic rollup</li>
            <li><code>lang</code>:       array of BCP 47 language tags of languages for which this module has localized resource bundles</li>
            <li><code>condition</code>: Specifies that the module should be loaded automatically if
                a condition is met.  This is an object with up to three fields:
                <ul>
                    <li><code>trigger</code> - the name of a module that can trigger the auto-load</li>
                    <li><code>test</code> - a function that returns true when the module is to be loaded.</li>
                    <li><code>when</code> - specifies the load order of the conditional module with regard to the position of the trigger module.
                        This should be one of three values: <code>before</code>, <code>after</code>, or <code>instead</code>.  The default is <code>after</code>.</li>
                </ul>
            </li>
        </ul>
    </li>
    <li><code>groups</code>: in 3.1.0, the groups config was added as an enhancement over the 'modules' config.  Each group can
    the <code>base</code>, <code>comboBase</code>, <code>root</code>, <code>combine</code>, and <code>modules</code>
    configs listed above.  These values are used for all of the modules listed in the group</li>
</ul>

<h2 id="Lang">Lang</h2>
<p><code>Lang</code> contains JavaScript language utilities and extensions that are used in the YUI library.

<pre class="code prettyprint">var Y = YUI();

&#x2F;&#x2F; true, an array literal is an array
Y.Lang.isArray([1, 2]);

&#x2F;&#x2F; false, an object literal is not an array
Y.Lang.isArray({&quot;one&quot;: &quot;two&quot;});

&#x2F;&#x2F; however, when declared as an array, it is true
function() {
    var a = new Array();
    a[&quot;one&quot;] = &quot;two&quot;;
    return Y.Lang.isArray(a);
}();

&#x2F;&#x2F; false, a collection of elements is like an array, but isn&#x27;t
Y.Lang.isArray(document.getElementsByTagName(&quot;body&quot;));

&#x2F;&#x2F; true, false is a boolean
Y.Lang.isBoolean(false);

&#x2F;&#x2F; false, 1 and the string &quot;true&quot; are not booleans
Y.Lang.isBoolean(1);
Y.Lang.isBoolean(&quot;true&quot;);

&#x2F;&#x2F; null is null, but false, undefined and &quot;&quot; are not
Y.Lang.isNull(null); &#x2F;&#x2F; true
Y.Lang.isNull(undefined); &#x2F;&#x2F; false
Y.Lang.isNull(&quot;&quot;); &#x2F;&#x2F; false

&#x2F;&#x2F; a function is a function, but an object is not
Y.Lang.isFunction(function(){}); &#x2F;&#x2F; true
Y.Lang.isFunction({foo: &quot;bar&quot;}); &#x2F;&#x2F; false

&#x2F;&#x2F; true, ints and floats are numbers
Y.Lang.isNumber(0);
Y.Lang.isNumber(123.123);

&#x2F;&#x2F; false, strings that can be cast to numbers aren&#x27;t really numbers
Y.Lang.isNumber(&quot;123.123&quot;);

&#x2F;&#x2F; false, undefined numbers and infinity are not numbers we want to use
Y.Lang.isNumber(1&#x2F;0);

&#x2F;&#x2F; true, objects, functions, and arrays are objects
Y.Lang.isObject({});
Y.Lang.isObject(function(){});
Y.Lang.isObject([1,2]);

&#x2F;&#x2F; false, primitives are not objects
Y.Lang.isObject(1);
Y.Lang.isObject(true);
Y.Lang.isObject(&quot;{}&quot;);

&#x2F;&#x2F; strings
Y.Lang.isString(&quot;{}&quot;); &#x2F;&#x2F; true
Y.Lang.isString({foo: &quot;bar&quot;}); &#x2F;&#x2F; false
Y.Lang.isString(123); &#x2F;&#x2F; false
Y.Lang.isString(true); &#x2F;&#x2F; false

&#x2F;&#x2F; undefined is undefined, but null and false are not
Y.Lang.isUndefined(undefined); &#x2F;&#x2F; true
Y.Lang.isUndefined(false); &#x2F;&#x2F; false
Y.Lang.isUndefined(null); &#x2F;&#x2F; false</pre>


</div>
        </div>

        <div id="sidebar" class="yui3-u">
            
                <div id="toc" class="sidebox">
                    <div class="hd">
                        <h2 class="no-toc">Table of Contents</h2>
                    </div>

                    <div class="bd">
                        <ul class="toc">
<li>
<a href="#loader-seed">The Loader Seed</a>
</li>
<li>
<a href="#base-seed">The Base Seed</a>
</li>
<li>
<a href="#why">Why the namespace change?</a>
</li>
<li>
<a href="#core">YUI Core</a>
</li>
<li>
<a href="#use">Use method</a>
</li>
<li>
<a href="#use-callback">Use callback</a>
</li>
<li>
<a href="#use-shorthand">Use shorthand</a>
</li>
<li>
<a href="#static-inclusion-vs-dynamic-loading">Static inclusion vs. dynamic loading</a>
</li>
<li>
<a href="#modulelist">Module List</a>
</li>
<li>
<a href="#yuiadd">Creating Custom Modules with YUI.add</a>
</li>
<li>
<a href="#loader">Loader</a>
</li>
<li>
<a href="#Lang">Lang</a>
</li>
</ul>
                    </div>
                </div>
            

            
                <div class="sidebox">
                    <div class="hd">
                        <h2 class="no-toc">Examples</h2>
                    </div>

                    <div class="bd">
                        <ul class="examples">
                            
                                
                                    <li data-description="Setting up a YUI Instance">
                                        <a href="yui-core.html">YUI Core</a>
                                    </li>
                                
                            
                                
                                    <li data-description="Working with multiple YUI instances.">
                                        <a href="yui-multi.html">Multiple Instances</a>
                                    </li>
                                
                            
                                
                                    <li data-description="On-demand loading of YUI and non-YUI assets">
                                        <a href="yui-loader-ext.html">YUI Loader - Dynamically Adding YUI and External Modules</a>
                                    </li>
                                
                            
                                
                                    <li data-description="Create Class Hierarchies with &#x60;extend&#x60;">
                                        <a href="yui-extend.html">Create Class Hierarchies with &#x60;extend&#x60;</a>
                                    </li>
                                
                            
                                
                                    <li data-description="Creating a composition-based class structure using &#x60;augment&#x60;">
                                        <a href="yui-augment.html">Compose Classes of Objects with &#x60;augment&#x60;</a>
                                    </li>
                                
                            
                                
                                    <li data-description="Add behaviors to objects or static classes with &#x60;mix&#x60;">
                                        <a href="yui-mix.html">Add Behaviors to Objects with &#x60;mix&#x60;</a>
                                    </li>
                                
                            
                                
                                    <li data-description="Combine data sets and create shallow copies of objects with &#x60;merge&#x60;">
                                        <a href="yui-merge.html">Combine Data Sets with &#x60;merge&#x60;</a>
                                    </li>
                                
                            
                                
                                    <li data-description="Check data types with the &#x60;Lang Utilities&#x60;">
                                        <a href="yui-isa.html">Check Data Types with &#x60;Lang&#x60;</a>
                                    </li>
                                
                            
                                
                                    <li data-description="Get information about the current user agent with &#x60;UA&#x60;">
                                        <a href="yui-ua.html">Browser Detection with &#x60;UA&#x60;</a>
                                    </li>
                                
                            
                                
                                    <li data-description="Working with YUI 2 in 3">
                                        <a href="yui-yui2.html">Working with YUI 2 in 3</a>
                                    </li>
                                
                            
                                
                                    <li data-description="Natively use YUI Gallery Modules">
                                        <a href="yui-gallery.html">Natively use YUI Gallery Modules</a>
                                    </li>
                                
                            
                        </ul>
                    </div>
                </div>
            

            
        </div>
    </div>
</div>

<script src="../assets/vendor/prettify/prettify-min.js"></script>
<script>prettyPrint();</script>

</body>
</html>
